feat!: abstract roots and union classes - #46

Closes #45.

The problem

A domain type that is naturally a discriminated union — a shared base, two variants, a union over the discriminant — was worse to model with this library than a plain entity. The issue reports three symptoms; the third is the one that changes how you model:

What the design turns on

Six measurements, taken before writing anything. Each is now a comment in the shipped source, because they are the reason the code looks like this:

M1 is why a union's class body is for statics. M2–M4 are why the root is tagless.

The API

abstract class AccountBase extends Entity.abstract("Account")(
  { id: AccountId, label: Label },
  { immutable: ["id"] },
) {
  abstract describe(): string;
  get slug(): string { return this.label.toLowerCase(); }
}

class Personal extends AccountBase.extend("Personal")({ kind: z.literal("personal") }) {
  override describe(): string { return `personal ${this.slug}`; }
}
class Business extends AccountBase.extend("Business")({ kind: z.literal("business") }) {
  override describe(): string { return `business ${this.slug}`; }
}

class Account extends Entity.union("kind", [Personal, Business]) {}
type AnyAccount = Entity.Instance<typeof Account>;   // Personal | Business

• Entity.abstract(name)(fields, options?) — tagless, make-less, no factory, none of the four schema members. Its _tag is string, and string & "Personal" reduces to "Personal" in the variant, which is what keeps M2 from biting. The name labels its defect message and never reaches an instance.
• extend rewires the new base's instance prototype onto the receiver's, so variant instanceof AccountBase is true and a behaviour-only intermediate abstract class between the two is picked up for free.
• Entity.union(…) returns a class. Account as a type is the members' shared root — or the empty type when they do not share one, via SoleType, which is what keeps M1 from firing while refusing to claim a supertype the members do not have. Account.make(row) still returns the exact Result<Personal | Business, InvalidEntity>.
• Entity.Instance<T> collapses the hand-maintained alias to one line that cannot drift.

M6 was wrong, and the correction is good news

The design spec claimed abstract members could not be enforced on variants, and prescribed implements SomeInterface as a workaround. That measurement was taken against a type-literal construct signature, which carries no abstractness. The shipped BehaviourOf<This> yields the real class type, and TypeScript propagates abstractness through the intersection:

TS2515: Non-abstract class 'Forgot' does not implement inherited abstract member
describe from class 'BaseInstance<…> & … & AccountBase'.

So abstract describe(): string on a root is a compiler-enforced obligation on every variant. implements ships nowhere. Pinned by an @ts-expect-error in base.test-d.ts.

The union deliberately strips that abstractness (Plain<T> in union.ts) — it has no instances, so inheriting a root's abstract members would demand implementations that could never run.

What a root does not carry

The rewiring is instance-prototype only, and three consequences follow. All are documented in reference/declaration.md and pinned by tests:

A variant declaring computed also replaces the root's, like generated and immutable — only invariants concatenate. That one drops a derived column rather than a rule, so it is now named explicitly.

Breaking

extend is no longer on an entity — an entity is final. This is the direct consequence of M2/M3: a concrete entity cannot carry behaviour into its extension at the type level, and a runtime that carried what the type did not would be worse than not carrying it. Rather than ship two extends with different fidelity, there is one, on the only receiver where it works.

// before
class Person extends Entity("Person")({ id: Id, name: Name }) {}
class PersonWithAge extends Person.extend("PersonWithAge")({ age: Age }) {}

// after
abstract class PersonBase extends Entity.abstract("Person")({ id: Id, name: Name }) {}
class Person extends PersonBase.extend("Person")({}) {}
class PersonWithAge extends PersonBase.extend("PersonWithAge")({ age: Age }) {}

minor, per 0.x. The changeset carries the migration; every fenced example in it was compiled before shipping.

The consumer gate

EntityStatic gains a sixth type parameter carrying the root's instance type, which is exactly the TS7056 band issues #31 and #32 shipped through. So it was measured rather than assumed:

• +16 extra branded fields on the widest variant still emit clean on 5.9.3. Comfortable margin.
• Naming ConstructedInstance<Tag, S, A, I> & B in the two zod slots, instead of spelling the intersection out twice more, is the headroom the parameter spends. Recorded in types.ts.
• examples/billing-domain is now four modules, so a root crossing a module boundary is under the two-compiler gate for the first time. Verified: index.d.ts opens with import { BillingDocumentBase } from "./root.js" rather than a synthesised local declare abstract class.
• Organization stays a plain, rootless entity — it is what keeps SoleType's Record<never, never> branch exercised in emit.

Test plan

• base.spec.ts / base.test-d.ts — fields and options carry over, shared behaviour runs on a variant, instanceof the root, behaviour-only intermediate root, the root has no instances, the seal still refuses a bare subclass, and the three "does not carry" cases above
• The sibling-variant equality pin proved discriminating: with the instanceof Base guard removed the test fails; restored, it passes. The shape it replaced passed guardless, so it pinned nothing
• union.spec.ts / union.test-d.ts — the class idiom, Account-as-a-type, the exact member union under P.tag, the empty-type fallback for members from different roots, and every pre-existing test untouched
• extend.spec.ts / extend.test-d.ts deleted, coverage mapped test-by-test into base.* first; the one pin that inverts is "extend carries declarations, not class-body members", which is the behaviour this change reverses
• format --check · lint · typecheck · test · knip · build — green in CI order, uncached, including the 5.9.3 consumer pass
• Docs: new explanation/unions-and-roots.md, reference and both how-tos reworked, eight files carrying stale extend references found and fixed

One thing I could not reproduce

A review reported that an unexported cross-module root breaks consumer emit with TS4020 through a branded field. It does not reproduce, and the shape may not be expressible: extend is a call on the value, so a root another module extends must be exported. No unmeasured diagnostic was written into the docs. The file split was kept anyway, on its own merit — it puts the cross-module emit path under the gate.

🤖 Generated with Claude Code